Drop AGENTS.md's migration list - #148
Merged
Merged
Conversation
`AGENTS.md` opened its migration list with `There are seven migrations.` and then walked through seven. It was true when #120 wrote it and has been false since #121; there are ten on `main`. A reader following that paragraph as the map it is meant to be gets handed an inventory that is short by three, and nothing in the paragraph says so. The count goes rather than moving to ten. A sentence naming a number plus a list of that many entries is a closed claim, and the next migration makes it a contradiction — falsified by anyone adding a file, without a line of `AGENTS.md` changing. A list with no count is a map: the next migration leaves a blank in it rather than a lie. The entries themselves were never wrong, and none of them is touched here. What replaces it says whose job it is to keep the list whole, because nothing said so before and that is the likeliest reason two migrations fell out of it. The three that add neither a table nor a column are `20260822050002_profile_own_reads.sql`, `20260827124213_account_emails.sql` and `20260830092253_apply_profile_children.sql` — the first two are exactly the two that went missing, which is two out of two and so an observation rather than a cause, but it is the axis the sentence names. The eighth entry is `my_profile()` and `my_credentials()` (#14), the ninth is `account_emails(uuid[])` (#123), the tenth is `apply_profile_children()` (#128). Each is written in the shape the seven above it use: what the migration establishes, and the one decision in it that a later change could undo without noticing. The eighth is somebody else's migration described in somebody else's document, so it is as close to the surrounding register as I could manage and should be rewritten freely. The prose below the list gains one clause. It already named `my_profile()` and `my_credentials()` as how the editor reads, and stopped at "saves them with a Server Action" — which reads as though the writes go straight out of the Server Action, and that is the shape #128 replaced. It now says the child tables are written through `apply_profile_children()` in one transaction. The paragraph is not restructured, and it grows from 462 words on one line to 924. Turning it into a list would make every future entry a one-line diff and would make this diff unreadable, so it is a separate question and not a contributor's to answer. Nothing in the repository lints or tests Markdown, and `ci.yml` detects a documentation-only branch and skips the build, so there is no run to point at here.
toruiwasa
marked this pull request as ready for review
September 2, 2026 23:31
davidtaing
previously approved these changes
Sep 4, 2026
davidtaing
left a comment
Collaborator
There was a problem hiding this comment.
Thank you @toruiwasa. I wonder if we should remove it from the AGENTS.md instead. Each time we create a migration means that we will have to update this each time.
The review on #148 asked whether the list should come out instead, and reading the ten entries against the migrations they describe says yes. Each one is a compression of the header of its own migration, including the first, whose note that the role and the hook are what everything later refers to reads as though it could only be said from outside the file: `admin_role_and_access_token_hook.sql` says it in its own second sentence. Nothing replaces it. `:403` already opens `Where the schema is decided, and in what order to read it`, and what it lists is `CONTEXT.md`, the ADRs and the spec rather than `supabase/migrations/`, which reads as deliberate: the schema is decided in the spec and applied in the migrations, and the list was inventorying the application. `:306` already says where the files are. Nothing moves either. The third entry's note about the seed was the one candidate, and `:306` describes `seed/`, `:462` records that the catalogue reaching production is a decision (#95) rather than a side effect of a deploy, and the catalogues migration sends a reader of the empty table to the same issue. The clause on `:349` from the commit below this one stays. A save's whole effect on the two child tables travelling through `apply_profile_children()` in one transaction is not a schema inventory, and the sentence it joins was stopping at the Server Action.
Collaborator
Author
|
Thanks @davidtaing, Reading the ten entries against the migrations they describe:
It is a summary sitting in a file that is always loaded, which is worth something, and I did weigh that. It has drifted twice, at #121 and #139, and a stale summary that gets trusted instead of the source is worse than no summary.
|
davidtaing
approved these changes
Sep 5, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
AGENTS.mdopened its Database section by enumerating the migrations, and the review on this pull request asked whether the list should come out rather than be finished. Reading the ten entries against the migrations they describe says yes, so this deletes the paragraph instead.Each entry is a compression of the header of its own migration, including the first, whose note that the role and the hook are what everything later refers to reads as though it could only be said from outside the file.
admin_role_and_access_token_hook.sql:4-5already saysThis is the thing every later policy and grant refers to.Nothing replaces it, and nothing moves
AGENTS.md:403already opensWhere the schema is decided, and in what order to read it, and what it lists isCONTEXT.md, the ADRs and the spec rather thansupabase/migrations/. That reads as deliberate: the schema is decided in the spec and applied in the migrations, and the list was inventorying the application.AGENTS.md:306already says where the files are.seed/,AGENTS.md:462records that the catalogue reaching production is a decision (Where the credential catalogue is permanently housed #95) rather than a side effect of a deploy, and the catalogues migration sends a reader of the empty table to the same issue.What I kept
The clause on
AGENTS.md:349about a save's whole effect on the two child tables travelling throughapply_profile_children()in one transaction. That is not a schema inventory, and the sentence it joins was stopping at the Server Action.Related issue
None. Two of the three entries this started out adding were from pull requests of mine (#139 and #147), so it began as finishing my own work rather than proposing new work. Happy to open one if you would rather.
Two commits
969c2f3is the original update, left as it is.c163563is the deletion, so the diff between the two is the review.Checklist
pnpm lintpassed, where applicable (Markdown only, nothing lints it)pnpm test:e2epassed, where applicable (Markdown only)Co-Authored-By,Generated with, or tool-attribution trailers